Image Buffers

Before an image can be displayed or processed, it must be loaded into an ImagXpress® buffer. ImagXpress maintains one buffer for each loaded image. The image buffer stores:

• DIB
• Image palette
• Image color profile
• Tags
• JPEG comments
• Undo image

A single ImagXpress control may manage multiple image buffers. The number of buffers is limited only by available memory and resources. Each image buffer within ImagXpress has a unique identifier (the image ID), assigned when the buffer is created.

The ProcessImageID property identifies the image buffer currently loaded, processed, or saved. The ProcessStatus property gets or sets the status of this buffer.

The ViewImageID identifies the image buffer that is currently being displayed. ViewStatus gets or sets the status of this buffer.

Creating a Buffer

An image buffer is created anytime ProcessImageID is assigned an ID for which no buffer currently exists. To create the new buffer, assign ProcessImageID an imageID identified by the GetUniqueImageID method, or one you know to be available (The IsValid method determines if the ID you wish to use is valid).

When the AutoAssignID property is True, ImagXpress automatically assigns an image ID (not currently in use) to ProcessImageID, creating a new buffer. When AutoAssignID is False, the ProcessImageID persists from when the control was last saved or as seen in design time.

Re-using a Buffer

An existing buffer can be reused. If an image is created, copied, or loaded into an image buffer that is already in use, the existing image buffer data is deleted and is replaced with the new image information. 

Populating a Buffer

A buffer can be populated with image data, using any of the load procedures described in the Load an Image section.

Deleting a Buffer

Call the CloseImage method to delete the specified image buffer and free up associated resources. If ViewImageID or ProcessImageID are set to the buffer when CloseImage is called, the DIB is deleted, but the buffer will not be closed. If ViewImageID is assigned to the image buffer, the control window will blank out as a result of the DIB being deleted.

Setting the AutoClose property to True instructs that when an ImagXpress control is destroyed, the image it was displaying (ViewImageID) is deleted if no other controls are viewing or processing that image. If another control is using the buffer, the DIB is deleted, but the image buffer will not be closed.

Monitoring the Status of a Buffer

Once a buffer is created, an image can be loaded, decoded, processed and saved using ImagXpress. The ImageStatus method identifies the current status of the specified image buffer. The ImageStatusChanged event generates every time the status of the image changes. The Cancel method cancels the current operation (loading & decompressing, processing, saving, etc.) on the specified image buffer.  The ProcessStatus property provides the status of the buffer pointed to by ProcessImageID. The ViewStatus property provides the status of the buffer pointed to by ViewImageID.

Assigning a Buffer to be Displayed in the Control Window

To display an image, set ViewImageID to the image buffer containing the image you wish to display. This image is displayed each time the control window paints. ViewStatus indicates the status (for example, opened, decoded, wait, saved, etc.) of the image in the ViewImageID buffer. 

Sharing a Buffer to be Displayed in Multiple Control Windows

Each ImagXpress control in the project can display only one image at a time. Sometimes it is necessary to display multiple views of the same image. A typical use would be to have a thumbnail version of the image and the full sized image displayed simultaneously. Or, the application may need to display a "before" and "after" view of an image with some image rendering options changed.

To view the same image using multiple ImagXpress controls, load the image into the first control and assign its ViewImageID to the second control's ViewImageID. Now the two views share the image.

// This code demonstrates how to view the same image using multiple ImagXpress controls
IX13a.FileName = "a.gif"
IX13b.ViewImageID = IX13a.ViewImageID

If a change occurs to the buffer shared by multiple controls, you may wish to repaint each of the control windows to reflect the change. Set AutoInvalidate property to True. This notifies all controls displaying an image buffer to repaint when a change occurs to the buffer.

In applications where buffers are shared between multiple ImagXpress controls, it may be necessary to specify that the buffer, not the control, is accessed when reading property information (See Enable Properties).

Assigning a Buffer to be Queried or Processed

Set ProcessImageID to the desired image buffer. If ProcessImageID is set to an image ID that does not exist yet, the buffer is automatically created. The image processed and the image viewed can be different.

// This code demonstrates how to set the desired image buffer
IX13.ProcessImageID = 502
IX13.Negate ' Do a reverse video on 'c.tif' but don't show it

IX13.ProcessImageID = 501
IX13.Negate ' Do a reverse video on 'a.tif' but don't show it

IX13.ViewImageID = 502 ' Finally show the reversed 'c.tif'

A single ImagXpress control may manage multiple images. The number of buffers is limited only by available memory and resources. By changing the ProcessImageID property you select which of the image buffers the following operations affects. You do not need to create or set-up buffers before using them. 

// This code demonstrates how to load five different images into five image buffers in one control
' The default ProcessImageID is 500
IX13.FileName = "a.tif"

IX13.ProcessImageID = 501
IX13.FileName = "b.tif"

IX13.ProcessImageID = 502
IX13.FileName = "c.tif"

IX13.ProcessImageID = 503
IX13.FileName = "d.gif"

IX13.ProcessImageID = 504
IX13.FileName = "e.bmp"

Modifying Data within the Image Buffer

Once an Image Buffer loads, the content can be modified (see Modify an Image, Modify Image Palette, Modify Image Metadata and Annotate an Image).

Querying Data within an Image Buffer

• Call GetImageHnd method (or GetImageHnd64 Method for 64-bit environments) to get the handle to the DIB associated with the specified image buffer.
• For additional information about the image, set ProcessImageID to the image you wish to query, then read:
  • ToHdib (method) -  to get the handle to the DIB.   ToHdib64 (method) - to get the handle to the DIB for 64-bit environments.
  • ToHBitmap (method) to get the handle to the BITMAP.
  • hPAL (read-only property) to get the handle to the palette associated with the specified image buffer.
  • RGBColorCountV method - returns three arrays, each containing a histogram of intensity values for the red, green and blue components of the DIB.
  • IFormat (read-only property) - returns the image's format.
  • IBPP (read-only property) - returns the image's bits per pixel.
  • IFileSize (read-only property) - returns the file size, in bytes.
  • IHeight (read-only property) - returns the height of the image, in pixels.
  • IWidth (read-only property) - returns the width of the image, in pixels.
  • IResUnits (read/write property) - the unit of measurement of resolution.
  • IResX (read/write property) - the image's X resolution. 
  • IResY (read/write property) - the image's Y resolution. 
  • ImagHeight (read-only property) - the image's height, in twips
  • ImagWidth (read-only property) - the image's width, in twips
  • DIBGetPalIndex method - an RGB value for a specified palette entry.
  • DIBGetPixel method - an RGB value for a specified pixel in the DIB.
  • JPEGGetComment method - returns the comment text of a specified comment.
  • TagFind, TagFirst and TagNext methods -  retrieve tag data items. 
  • TagData (read-only property) - retrieve tag data
• To display information about an image being viewed, set ViewImageID to the image you wish to display, then call ShowViewImageInfo method.

Managing Buffer Memory

When the hBMP property is called, a bitmap version of the image is created and placed at hBMP. When you are done with this bitmap, you must free up the bitmap pointer. To do this, call the gdi32.dll entry DeleteObject(HOBJ)hBitmap.

Compressing Image Data in Memory When Not in Use

The CompressInMemory property specifies whether the image is compressed when stored in memory. This can be useful when displaying many ImagXpress objects at the same time. For images with bit-levels greater than 1, compressing in memory results in only a small amount of compression, but at a high price of reduced performance. For this reason, CompressInMemory is most useful for 1-bit images.

Alternatively, the user can compress an image in memory by calling the SaveToBuffer property, setting the compression type to whatever is most desirable. When the image is needed, use LoadBuffer method to load the image.

©2019. Accusoft Corporation. All Rights Reserved.